Authentication

External systems can have access to the Hive APIs through the use of service accounts and by requesting and submitting an access token. The following steps should be taken to correctly authenticate.

Configure a service account

External systems can have access to the Hive APIs through the use of service accounts. These accounts are different from human user accounts. They are created by the Hive administrator of the customer and can be managed in the User Manager. They need to be linked to a Mediagenix Base platform user that has the Server user check box selected. This user should have the same permissions as required by a regular user to create, edit and delete the concept of the API, such as content, transmissions etc. Otherwise, the service account will not be authorized to use the API endpoints.

In the User Manager, on the Service accounts tab, a user can create a new service account by clicking on the Create service accounts button.

The side pane that opens allows to fill in the:

  • Service name

  • Password

  • Repeat password

  • Internal information: An optional text field.

  • Base user: Link the base user that has the Server user check box selected and the required permissions, as explained above.

After saving the service account with a suitable password, the user can use these details to authenticate via a dedicated call in the next steps.

Obtain a token

Approach

Access to the API is restricted with JSON Web tokens (JWT). The general approach is as follows:

  1. A JWT is requested by submitting credentials to the login URL.

  2. In case the credentials are valid, a JWT is generated by Mediagenix Hive platform.

  3. The JWT is returned to the client.

  4. For each request, the JWT must be included in the header.

  5. Hive reads the JWT for every request and validates it before processing the message.

  6. A response message is returned.

Request a token

To request a token, a POST call must be sent to a dedicated login path:

POST https://auth-api.develop.mediagenix.io/login

The headers of the call should contain the following key-value pair:

  • Content-Type: application/json

The body should contain the following attributes:

  • username: The username of the service account.

  • password: The password of the service account.

An example of the full request in curl:

 curl --location --request POST 'https://auth-api.develop.mediagenix.io/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "API",
    "password": "yourPassword"
}'

The response of the login call contains the access token.

An example:

{ 
  "accessToken": "eyJra..."
}

Authenticate using the token

Once a token is returned, it must be included in the authorization header of every API call using the following format:

Authorization: Bearer <token>

The header in an actual request would look as follows:

'Authorization: Bearer eyJra...'

The same token can be reused as long as it has not expired yet. As specified above, tokens for the Hive APIs are fixed to expire after an hour.

In case any problems occur with the authentication, the following status codes can be returned:

Status code Description
401 Unauthorized

This response is returned in the following cases:

  • The request does not contain credentials.

  • The request does not contain a JWT token or contains an invalid JWT token.

403 Forbidden

This response is returned in the following cases:

  • Wrong credentials.

  • The JWT token has expired.

  • No permissions to read or update the resource.